<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Global std_out</title>
<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../../process/reference.html#header.boost.process.io_hpp" title="Header &lt;boost/process/io.hpp&gt;">
<link rel="prev" href="std_in.html" title="Global std_in">
<link rel="next" href="std_err.html" title="Global std_err">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
<td align="center"><a href="../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="std_in.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../process/reference.html#header.boost.process.io_hpp"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="std_err.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="refentry">
<a name="boost.process.std_out"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2><span class="refentrytitle">Global std_out</span></h2>
<p>boost::process::std_out</p>
</div>
<h2 xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv-title">Synopsis</h2>
<div xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv"><pre class="synopsis"><span class="comment">// In header: &lt;<a class="link" href="../../process/reference.html#header.boost.process.io_hpp" title="Header &lt;boost/process/io.hpp&gt;">boost/process/io.hpp</a>&gt;

</span><span class="emphasis"><em><span class="identifier">unspecified</span></em></span> std_out<span class="special">;</span></pre></div>
<div class="refsect1">
<a name="id-1.3.31.9.16.19.4"></a><h2>Description</h2>
<p>This property allows to set the output stream for the child process.</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>The Semantic is the same as for <a class="link" href="std_err.html" title="Global std_err">std_err</a> </p></td></tr>
</table></div>
<p>
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p><code class="computeroutput">std_err</code> and <code class="computeroutput">std_out</code> can be combined into one stream, with the <code class="computeroutput">operator &amp;</code>, i.e. <code class="computeroutput">std_out &amp; std_err</code>.</p></td></tr>
</table></div>
<p>
</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="namespaceboost_1_1process_1stdout_details"></a>Details</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="sect2"><a href="std_out.html#namespaceboost_1_1process_1stdout_file">File Input</a></span></dt>
<dt><span class="sect2"><a href="std_out.html#namespaceboost_1_1process_1stdout_pipe">Pipe Output</a></span></dt>
<dt><span class="sect2"><a href="std_out.html#namespaceboost_1_1process_1stdout_async_pipe">Asynchronous Pipe Output</a></span></dt>
<dt><span class="sect2"><a href="std_out.html#namespaceboost_1_1process_1stdout_close">Close</a></span></dt>
<dt><span class="sect2"><a href="std_out.html#namespaceboost_1_1process_1stdout_null">Null</a></span></dt>
</dl></div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="namespaceboost_1_1process_1stdout_file"></a>File Input</h3></div></div></div>
<p>The file I/O simple redirects the stream to a file, for which the possible types are</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><code class="computeroutput">boost::filesystem::path</code></p></li>
<li class="listitem"><p><code class="computeroutput">std::basic_string&lt;char_type&gt;</code></p></li>
<li class="listitem"><p><code class="computeroutput">const char_type*</code></p></li>
<li class="listitem"><p><code class="computeroutput">FILE*</code></p></li>
</ul></div>
<p>
</p>
<p>with <code class="computeroutput">char_type</code> being either <code class="computeroutput">char</code> or <code class="computeroutput">wchar_t</code>.</p>
<p>FILE* is explicitly added, so the process can easily redirect the output stream of the child to another output stream of the process. That is:</p>
<pre class="programlisting"><span class="identifier">system</span><span class="special">(</span><span class="string">"ls"</span><span class="special">,</span> <span class="identifier">std_out</span> <span class="special">&lt;</span> <span class="identifier">stdin</span><span class="special">)</span><span class="special">;</span>
</pre>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>If the launching and the child process use the input, this leads to undefined behaviour.</p></td></tr>
</table></div>
<p>
A syntax like <code class="computeroutput">system("ls", std_out &gt; std::cerr)</code> is not possible, due to the C++ implementation not providing access to the handle.</p>
<p>The valid expressions for this property are</p>
<pre class="programlisting"><span class="identifier">std_out</span> <span class="special">&lt;</span> <span class="identifier">file</span><span class="special">;</span>
<span class="identifier">std_out</span> <span class="special">=</span> <span class="identifier">file</span><span class="special">;</span>
</pre>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="namespaceboost_1_1process_1stdout_pipe"></a>Pipe Output</h3></div></div></div>
<p>As explained in the corresponding section, the boost.process library provides a <a class="link" href="async_pipe.html" title="Class async_pipe">async_pipe</a> class which can be used to communicate with child processes.</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>Technically the <a class="link" href="async_pipe.html" title="Class async_pipe">async_pipe</a> works like a synchronous pipe here, since no asio implementation is used by the library here. The asynchronous operation will then however not end if the process is finished, since the pipe remains open. You can use the async_close function with on_exit to fix that.</p></td></tr>
</table></div>
<p>
Valid expressions with pipes are these:</p>
<pre class="programlisting"><span class="identifier">std_out</span> <span class="special">&gt;</span> <span class="identifier">pipe</span><span class="special">;</span>
<span class="identifier">std_out</span> <span class="special">=</span> <span class="identifier">pipe</span><span class="special">;</span>
</pre>
<p>Where the valid types for <code class="computeroutput">pipe</code> are the following:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><code class="computeroutput"><a class="link" href="basic_pipe.html" title="Class template basic_pipe">basic_pipe</a></code></p></li>
<li class="listitem"><p><code class="computeroutput"><a class="link" href="async_pipe.html" title="Class async_pipe">async_pipe</a></code></p></li>
<li class="listitem"><p><code class="computeroutput"><a class="link" href="basic_ipstream.html" title="Class template basic_ipstream">basic_ipstream</a></code></p></li>
<li class="listitem"><p><code class="computeroutput"><a class="link" href="basic_pstream.html" title="Class template basic_pstream">basic_pstream</a></code></p></li>
</ul></div>
<p>
</p>
<p>Note that the pipe may also be used between several processes, like this:</p>
<pre class="programlisting"><span class="identifier">pipe</span> <span class="identifier">p</span><span class="special">;</span>
<span class="identifier">child</span> <span class="identifier">c1</span><span class="special">(</span><span class="string">"nm"</span><span class="special">,</span> <span class="string">"a.out"</span><span class="special">,</span> <span class="identifier">std_out</span><span class="special">&gt;</span><span class="identifier">p</span><span class="special">)</span><span class="special">;</span>
<span class="identifier">child</span> <span class="identifier">c2</span><span class="special">(</span><span class="string">"c++filt"</span><span class="special">,</span> <span class="identifier">std_in</span><span class="special">&lt;</span><span class="identifier">p</span><span class="special">)</span><span class="special">;</span>
</pre>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="namespaceboost_1_1process_1stdout_async_pipe"></a>Asynchronous Pipe Output</h3></div></div></div>
<p>Asynchronous Pipe I/O classifies communication which has automatically handling of the async operations by the process library. This means, that a pipe will be constructed, the async_read/-write will be automatically started, and that the end of the child process will also close the pipe.</p>
<p>Valid types for pipe I/O are the following:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><code class="computeroutput">boost::asio::mutable_buffer</code> <a href="#ftn.id-1.3.31.9.16.19.4.4.4.4.1.1.1.2" class="footnote" name="id-1.3.31.9.16.19.4.4.4.4.1.1.1.2"><sup class="footnote">[32]</sup></a> </p></li>
<li class="listitem"><p><code class="computeroutput">boost::asio::streambuf</code></p></li>
<li class="listitem"><p><code class="computeroutput">std::future&lt;std::vector&lt;char&gt;&gt;</code></p></li>
<li class="listitem"><p><code class="computeroutput">std::future&lt;std::string&gt;</code></p></li>
</ul></div>
<p>
</p>
<p>Valid expressions with pipes are these:</p>
<pre class="programlisting"><span class="identifier">std_out</span> <span class="special">&gt;</span> <span class="identifier">buffer</span><span class="special">;</span>
<span class="identifier">std_out</span> <span class="special">=</span> <span class="identifier">buffer</span><span class="special">;</span>
<span class="identifier">std_err</span> <span class="special">&gt;</span> <span class="identifier">buffer</span><span class="special">;</span>
<span class="identifier">std_err</span> <span class="special">=</span> <span class="identifier">buffer</span><span class="special">;</span>
<span class="special">(</span><span class="identifier">std_out</span> <span class="special">&amp;</span> <span class="identifier">std_err</span><span class="special">)</span> <span class="special">&gt;</span> <span class="identifier">buffer</span><span class="special">;</span>
<span class="special">(</span><span class="identifier">std_out</span> <span class="special">&amp;</span> <span class="identifier">std_err</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">buffer</span><span class="special">;</span>
</pre>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p><code class="computeroutput">boost::asio::buffer</code> is also available in the <code class="computeroutput">boost::process</code> namespace.</p></td></tr>
</table></div>
<p>
</p>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>This feature requires <code class="computeroutput">boost/process/async.hpp</code> to be included and a reference to <code class="computeroutput">boost::asio::io_context</code> to be passed to the launching function.</p></td></tr>
</table></div>
<p>
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="namespaceboost_1_1process_1stdout_close"></a>Close</h3></div></div></div>
<p>The out stream can be closed, so it cannot be write from. This will lead to an error when attempted.</p>
<p>This can be achieved by the following syntax.</p>
<pre class="programlisting"><span class="identifier">std_out</span> <span class="special">&gt;</span> <span class="identifier">close</span><span class="special">;</span>
<span class="identifier">std_out</span> <span class="special">=</span> <span class="identifier">close</span><span class="special">;</span>
<span class="identifier">std_out</span><span class="special">.</span><span class="identifier">close</span><span class="special">(</span><span class="special">)</span><span class="special">;</span>
</pre>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="namespaceboost_1_1process_1stdout_null"></a>Null</h3></div></div></div>
<p>The output stream can be redirected to write to the null-device, which means that all output is discarded.</p>
<p>The syntax to achieve that has the following variants:</p>
<pre class="programlisting"><span class="identifier">std_out</span> <span class="special">&gt;</span> <span class="identifier">null</span><span class="special">;</span>
<span class="identifier">std_out</span> <span class="special">=</span> <span class="identifier">null</span><span class="special">;</span>
<span class="identifier">std_out</span><span class="special">.</span><span class="identifier">null</span><span class="special">(</span><span class="special">)</span><span class="special">;</span>
</pre>
<p> </p>
</div>
</div>
</div>
<div class="footnotes">
<br><hr style="width:100; text-align:left;margin-left: 0">
<div id="ftn.id-1.3.31.9.16.19.4.4.4.4.1.1.1.2" class="footnote"><p><a href="#id-1.3.31.9.16.19.4.4.4.4.1.1.1.2" class="para"><sup class="para">[32] </sup></a> Constructed with <code class="computeroutput">boost::asio::buffer</code></p></div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2006-2012 Julio M. Merino Vidal, Ilya Sokolov,
      Felipe Tanus, Jeff Flinn, Boris Schaeling<br>Copyright © 2016 Klemens D. Morgenstern<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="std_in.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../process/reference.html#header.boost.process.io_hpp"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="std_err.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
